home *** CD-ROM | disk | FTP | other *** search
/ Amiga Plus 1996 #6 / Amiga Plus CD - 1996 - No. 06.iso / pd / texte / wordwrap / wordwrap.doc < prev    next >
Text File  |  1996-08-09  |  4KB  |  103 lines
  1.  
  2.  
  3.                              WordWrap
  4.                              ========
  5.  
  6.  
  7. "wordwrap" is a text filter that rearranges the line breaks in a plain
  8. ASCII text, preserving paragraphs (or ignoring them, if you wish :)=).
  9. I wrote it, because I often encounter strangely formatted but large texts 
  10. on usenet -- and because I don't own an editor like TurboText that can 
  11. reformat paragraphs. ;-)
  12.  
  13.  
  14. Usage
  15. -----
  16.  
  17.   wordwrap [options] <original_file >new_file
  18.  
  19. options are:
  20.  
  21.     -l<len>         output line length, defaults to 75
  22.     -b              protect blank lines
  23.     -i              protect indentation
  24.     -i<indent>       " , enforcing a fixed indentation width
  25.     -s<maxlen>      protect short input lines
  26.  
  27.  
  28. Notes
  29. -----
  30.  
  31. Try "-l1": this will create ouput with one word per line. Fun! ;-)
  32.     The -b option that preserves blank lines is highly recommended in all
  33. cases. You will find very few texts that look good without it.
  34.     The -i option assumes that each indented line is the start of a new
  35. paragraph, like in this section. This will also protect the line break
  36. of indented blocks like the options list above or the heading on top of
  37. this document.
  38.     Maybe you don't like the way these paragraphs are indented by only 
  39. four spaces each (or perhaps you've even got a document with a variable
  40. indentation width): Try -i6, this will indent anything in the text that
  41. isn't left aligned by exactly 6 spaces, even those parts that were indented
  42. by tabs.
  43.     When you wordwrap this text you should notice how the dashes 
  44. underlining the section headings are wrapped in an unwanted way. Try -s20, 
  45. this will insert a line break after each input line containing less than 
  46. 20 non-blank characters: voilà. B.t.w., it's hard to do any damage with 
  47. this option, you might have even said -s40 or -s60. In a text originally
  48. formatted for 75 columns like this, it is unlikely to encounter a line
  49. shorter than 60 characters within a paragraph.
  50.  
  51.  
  52. Examples
  53. --------
  54.  
  55. Most of these examples do not redirect their output, because I think
  56. playing with the options is nicer this way.
  57.  
  58.   wordwrap <wordwrap.doc                   ; can you read this? :)
  59.   wordwrap <wordwrap.doc -b                ; much better
  60.   wordwrap <wordwrap.doc -b -s20           ; makes "underline" work
  61.   wordwrap <wordwrap.doc -b -s20 -i        ; for those indented paragraphs
  62.   wordwrap <wordwrap.doc -b -s20 -i -l40   ; now try some text widths
  63.   wordwrap <wordwrap.doc -b -s20 -i -l60   ; this is nice ...
  64.   wordwrap <wordwrap.doc -b -s20 -i -l60 >wwr.doc          ; keep it
  65.  
  66. When you look at the output "wwr.doc" you will notice that it still
  67. needs some editing. This will be true for most real-life applications,
  68. too. Nevertheless, I think "wordwrap" does a damn good job.
  69.   
  70.  
  71. Known problems
  72. --------------
  73.  
  74. The -i and -s options cannot fully prevent that the alignment of tables 
  75. or ASCII art diagrams is recklessly destroyed. However, I am not going to 
  76. take any further efforts in this matter. You must either restore such 
  77. sections manually, or insert a copy from the original document. If this
  78. occurs too frequently, well, tough luck: Don't reformat such a text with 
  79. "wordwrap" then.
  80.  
  81. Lines indented with tab characters are likely to become too long in the
  82. output, because "wordwrap" knows nothing about tabs and counts them just
  83. like simple spaces. In some cases -i4 or -i8 instead of -i may help. 
  84. If this is not what you want, you must first convert all tabs to spaces, 
  85. using a utility like "detab" (or maybe your text editor).
  86.  
  87. The notorious combination CR/LF is no problem (the CR's are simply 
  88. stripped), however LF/CR (note the reverse order) might confuse "wordwrap" 
  89. when using -i. I don't know if this ever occurs, but if it does, you will
  90. have to use a different text filter to strip those CR's first.
  91.  
  92.  
  93. Credits
  94. -------
  95.  
  96. This program was written using EdWord and the GNU C compiler.
  97.  
  98. "wordwrap" is Freeware/Mailware: If you like it, send me E-Mail:
  99.  
  100.   wnoeker@t-online.de
  101.   (Wilhelm Noeker)
  102.  
  103.